名前¶

stat, fstat, lstat - ファイルの状態を取得する

書式¶

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

int stat(const char *path, struct stat *buf);
int fstat(int fd, struct stat *buf);
int lstat(const char *path, struct stat *buf);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

lstat():

説明¶

これらの関数はファイルについての情報を返す。 ファイルそのものに対するアクセス許可は必要としないが、 —stat() と lstat() の場合には — そのファイルへ至る path を構成する全てのディレクトリに対する 実行 (検索) 許可が必要である。

stat() は path で指定されたファイルの状態を取得して buf へ格納する。

lstat() は stat() と同じであるが、 path がシンボリックリンクの場合、リンクが参照しているファイルではなく、 リンク自身の状態を取得する点が異なる。

fstat() は stat() と同じだが、 状態を取得するファイルをファイル・ディスクリプタ fd で指定する。

これらのシステムコールはいずれも、結果を stat 構造体に入れて返す。 stat 構造体には以下のフィールドが含まれている:

struct stat {


    dev_t     st_dev;     /* ファイルがあるデバイスの ID */


    ino_t     st_ino;     /* inode 番号 */


    mode_t    st_mode;    /* アクセス保護 */


    nlink_t   st_nlink;   /* ハードリンクの数 */


    uid_t     st_uid;     /* 所有者のユーザ ID */


    gid_t     st_gid;     /* 所有者のグループ ID */


    dev_t     st_rdev;    /* デバイス ID (特殊ファイルの場合) */


    off_t     st_size;    /* 全体のサイズ (バイト単位) */


    blksize_t st_blksize; /* ファイルシステム I/O での


                             ブロックサイズ */


    blkcnt_t  st_blocks;  /* 割り当てられた 512B のブロック数 */


    time_t    st_atime;   /* 最終アクセス時刻 */


    time_t    st_mtime;   /* 最終修正時刻 */


    time_t    st_ctime;   /* 最終状態変更時刻 */
};

st_dev フィールドは、このファイルが存在するデバイスを示す (マクロ major(3), minor(3) は、このフィールドのデバイス ID を分解するのに役立つだろう)。

st_rdev フィールドは、このファイル (inode) が表すデバイスを示す。

st_size フィールドは、(通常のファイルかシンボリックリンクの場合に) ファイルの大きさをバイト単位で示す。 シンボリックリンクの大きさは、 シンボリックリンクに含まれている パス名の長さ (終端の NULL バイトは含まない) である。

st_blocks フィールドは、ファイルの大きさを 512 バイトのブロックサイズ単位で示す フィールドは、ファイルに割り当てされたブロック数を 512 バイト単位で示す。 (ファイルに穴があるような場合、この値は st_size/512 より小さくなることもある)。

st_blksize フィールドは、効率的にファイルシステム I/O ができる「好ましい」 ブロックサイズを示す (もっと小さい単位でファイルに書き込みを行うと、 読み出し--修正--再書き込みといった非効率な動作になってしまうかもしれない)。

全ての Linux のファイルシステムが全ての時間フィールドを 実装しているわけではない。 ファイルやディレクトリのアクセスが st_atime フィールドを更新しないようなかたちでマウントできるファイルシステムもある。 (mount(8) の noatime, nodiratime, relatime や mount(2) の関連する情報を参照)。 また、ファイルが O_NOATIME 付きでオープンされている場合には st_atime は更新されない。 open(2) 参照。

st_atime フィールドはファイルアクセスがあった場合に変更される (例えば、 execve(2), mknod(2), pipe(2), utime(2) を使用した場合や read(2) で 1 バイト以上読み込んだ場合など)。 mmap(2) などの他のルーチンでは、 st_atime は更新されることもあれば、そうでない場合もある。

st_mtime フィールドは、ファイルが修正された場合に変更される (例えば、 mknod(2), truncate(2), utime(2) を使用した場合や write(2) で 1 バイト以上書き込みをした場合など)。 さらに、ディレクトリの st_mtime は、そのディレクトリで ファイルが作成されたり削除されたりすると変更される。 st_mtime フィールドは 所有者やグループやハード・リンク数やモードの変更では変更 されない。

st_ctime フィールドは書き込みや inode 情報 (所有者、グループ、リンク数、モードなど) の 設定によって変更される。

以下の POSIX マクロは、 st_mode フィールド で使用されるファイル種別のチェックのために定義されている :

以下のフラグが st_mode フィールド用に定義されている:

set-group-ID bit (S_ISGID) にはいくつかの特殊な使用法がある: ディレクトリに設定した場合には、そのディレクトリが BSD 方式で使用される ことを示す。つまり、そのディレクトリに作成されたファイルのグループID は 作成したプロセスの実効 (effective) グループID ではなく、ディレクトリの グループID を継承する。また、そのディレクトリに作成されたディレクトリにも S_ISGID ビットが設定される。グループ実行ビット (S_IXGRP) が設定されていないファイルに設定された場合は、 set-group-ID ビットはファイル/レコードの 強制的な (mandatory) ロックを表す。

ディレクトリにスティッキービット (S_ISVTX) が設定された場合は、 そのディレクトリのファイルの名前を変更したり、削除したりできるのは、 そのファイルの所有者か、そのディレクトリの所有者か、特権プロセス だけとなる。

返り値¶

成功した場合、0 が返される。 失敗した場合、 -1 が返され、 errno に適切な値がセットされる。

エラー¶

EACCES

path が所属するディレクトリとその上位のディレクトリのいずれかに 対する検索許可がなかった (path_resolution(7) も参照のこと)。

EBADF

fd が不正である。

EFAULT

アドレスが間違っている。

ELOOP

パスを辿る際に解決すべきシンボリックリンクが多過ぎた。

ENAMETOOLONG

path が長過ぎる。

ENOENT

path の構成要素が存在しないか、 path が空文字列である。

ENOMEM

カーネルのメモリが足りない。

ENOTDIR

path の前半部分 (prefix) の構成要素がディレクトリではない。

EOVERFLOW

path または fd が、ファイルサイズ、inode 番号、ブロック数が それぞれ off_t 型、 ino_t 型、 blkcnt_t 型で表現できないファイルを 参照している。このエラーが起こるのは、例えば、32 ビットプラットフォーム上で -D_FILE_OFFSET_BITS=64 を指定せずにコンパイルされたアプリケーションが、 ファイルサイズが (1<<31)-1 バイトを超えるファイルに対して stat() を呼び出した場合である。

準拠¶

これらのシステムコールは SVr4, 4.3BSD, POSIX.1-2001 に準拠している。 stat() と fstat() コールは SVr4, SVID, POSIX, X/OPEN, 4.3BSD に準拠している。 lstat() コールは 4.3BSD と SVr4 に準拠している。

POSIX.1-2001 では、シンボリックリンクに対する lstat() で 有効な情報を返すように求められていたのは、 stat 構造体の st_size と st_mode のファイル種別要素だけであった。 POSIX.1-2008 では規定が厳しくなり、 lstat() は st_mode の アクセス許可ビット以外の全てのフィールドに有効な情報を返すことが 求められるようになっている。

st_blocks と st_blksize フィールドの使用はあまり移植性がない (これらのフィールドは BSD によって導入された。 システムごとに解釈が 異なっており、 NFS マウントの場合には同じシステムでも異なる可能性がある)。 <sys/stat.h> から blkcnt_t の blksize_t 型定義を 読み込みたい場合は、(どのヘッダファイルをインクルードするよりも前に) _XOPEN_SOURCE を 500 以上の値で定義すること。

POSIX.1-1990 には S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX 定数に関する 記述はなかったが、代わりに S_ISDIR() のようなマクロを使用するように 要求していた。 S_IF* 定数は POSIX.1-2001 以降には存在する。

マクロ S_ISLNK() と S_ISSOCK() は POSIX.1-1996 にはないが、 POSIX.1-2001 には両方とも存在する。 前者は SVID 4 に、後者は SUSv2 に 由来している。

UNIX V7 (とその後のシステム) は S_IREAD, S_IWRITE, S_IEXEC を持っており、 POSIX はその同義語として S_IRUSR, S_IWUSR, S_IXUSR を規定している。

注意¶

カーネル 2.5.48 以降では、 stat 構造体は 3 つのファイルのタイムスタンプ 関連のフィールドでナノ秒単位の精度に対応している。 glibc では、機能検査 マクロ _BSD_SOURCE か _SVID_SOURCE が定義された場合に、各フィールドの ナノ秒の情報を st_atim.tv_nsec という形式の名前で公開する。 これらのフィールドは POSIX.1-2008 で規定されており、 バージョン 2.12 以降の glibc では、 _POSIX_C_SOURCE が 200809L 以上の値で定義されるか、 _XOPEN_SOURCE が 700 以上の値で定義された場合に、 これらのフィールドが公開される。 上記のマクロのいずれも定義されていない場合、ナノ秒の値は st_atimensec という形式の名前で公開される。 秒より細かいタイムスタンプをサポートしていないファイルシステムでは、 ナノ秒のフィールドは 0 に設定される。

Linux では、 lstat() は一般には自動マウント動作 (automounter action) の きっかけとならないが、 stat() はきっかけとなる (fstatat(2) を参照)。

/proc ディレクトリ以下にあるファイルのほとんどでは、 stat() を呼び出した際に、 st_size フィールドにファイルサイズが返されない。 代わりに st_size フィールドには 0 が返される。

例¶

以下のプログラムは stat() を呼び出し、返ってきた stat 構造体のフィールドのいくつかを表示する。

#include <sys/types.h>
#include <sys/stat.h>
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{


    struct stat sb;


    if (argc != 2) {


        fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    if (stat(argv[1], &sb) == -1) {


        perror("stat");


        exit(EXIT_FAILURE);


    }


    printf("File type:                ");


    switch (sb.st_mode & S_IFMT) {


    case S_IFBLK:  printf("block device\n");            break;


    case S_IFCHR:  printf("character device\n");        break;


    case S_IFDIR:  printf("directory\n");               break;


    case S_IFIFO:  printf("FIFO/pipe\n");               break;


    case S_IFLNK:  printf("symlink\n");                 break;


    case S_IFREG:  printf("regular file\n");            break;


    case S_IFSOCK: printf("socket\n");                  break;


    default:       printf("unknown?\n");                break;


    }


    printf("I-node number:            %ld\n", (long) sb.st_ino);


    printf("Mode:                     %lo (octal)\n",


            (unsigned long) sb.st_mode);


    printf("Link count:               %ld\n", (long) sb.st_nlink);


    printf("Ownership:                UID=%ld   GID=%ld\n",


            (long) sb.st_uid, (long) sb.st_gid);


    printf("Preferred I/O block size: %ld bytes\n",


            (long) sb.st_blksize);


    printf("File size:                %lld bytes\n",


            (long long) sb.st_size);


    printf("Blocks allocated:         %lld\n",


            (long long) sb.st_blocks);


    printf("Last status change:       %s", ctime(&sb.st_ctime));


    printf("Last file access:         %s", ctime(&sb.st_atime));


    printf("Last file modification:   %s", ctime(&sb.st_mtime));


    exit(EXIT_SUCCESS);
}

関連項目¶

access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capabilities(7), symlink(7)

この文書について¶

この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。